R markdown basics

R Markdown

(Copied from this)

You can use R Markdown (.Rmd) to:

• save and execute code
• generate high quality, reproducible reports that can be shared with an audience

Basic structure consists of:

• YAML metadata
• Text (markdown)
• Code chunks

Can edit in Visual mode, more like a Word doc. (Click on ‘Visual’, next to ‘Source’ at the top of the code editor.)

To see your R markdown output file (e.g. html), you knit the .Rmd file by clicking the Knit button at the top of the code editor or ctrl-shift-k.

YAML

The YAML header is used to set the output format and output options.

Here, we’ve added a table of contents using the toc: true.

Have a look at the cheat sheet and try to add some more features:

Exercise: Make the table of contents floating.

Add toc_float: TRUE to the YAML.

Exercise: Give an option to download the .Rmd source code.

Add code_download: TRUE to the YAML.

Exercise: Hide all the code chunks by default and allow users to show/hide code as desired.

Add code_folding: “hide” to the YAML.

We can generate a custom R markdown template to use in the future.

Text

Makes clear documentation easier.

You can navigate through the headers (#Heading 1, ##Heading 2 etc) like a table of contents in the code editor by clicking ‘Outline’ in the top right.

Have a look at the cheat sheet and try the following exercises.

Exercise: Bold and italicise some words in the list below.

• Always leave a blank line between a list and the text above for the bullet points to render properly
• assessing current practice (italics)
• recording an action plan (bold)
• monitoring quality improvement

Exercise: Create a link to the page on Impact reports on the NICE website.

See impact reports.

Exercise: Embed an image of the NICE logo and add some alt text.

This standard method doesn’t seem to allow adding alt text, but the text in the square brackets is displayed as a caption at the bottom of the image.

NICE logo

Need to use this method with fig.alt in chunk options for alt text.

knitr::include_graphics("https://www.nice.org.uk/Media/Default/About/Branding-guidelines/Logos/master-logo1.png")

This line contains some inline code to give the time of rendering: 2022-06-08 13:05:26.

Code chunks

Exercise: Insert a code chunk. Try using a keyboard shortcut (ctrl-alt-i).

Labelling your chunks (e.g. ‘load_doacs’ in the chunk below) means you can navigate to each section easily via the button at the bottom of the code editor (orange square with hash symbol).

Tabs

A demo using the DOACS data from before.

The line chart and table sections are in tabs below the header ‘Tabs’ because we’ve specified {.tabset}.

You should run all the chunks above a chunk before running the chunk itself to make sure your code works sequentially, when working in the code editor (i.e. not knitting). Click on the grey triangle with the green bar (‘Run all chunks above’) in the top right of a chunk (ctrl-alt-shift-p).

To run a chunk, ctrl-shift-enter with the cursor anywhere in the chunk (or the green play button).

Line chart

Exercise: Plot a line chart showing prescribing of all doacs over the last 2 years (reuse previous code from DOACS exercises). Try making it interactive by using the function ggplotly() from the plotly package (install the package first).

Table

There are many packages available for plotting tables in R markdown.

We’ll use reactable here. Install the package.

Exercise: Modify this table to make it filterable and searchable. Try using an aggregate function to give the sum items for each chemical.

doacs_df %>% 
    filter(year(date) == 2020) %>% 
    group_by(chemical, date) %>% 
    summarise(sum_items = sum(items)) %>% 
    reactable(
        .,
        filterable = TRUE,
        searchable = TRUE,
        groupBy = "chemical",
        columns = list(
            sum_items = colDef(aggregate = "sum")
        )
    )

Chunk options

Chunk options allow control over chunk outputs. See some options here.

Exercise: Add an option to the load_doacs chunk so the chunk still runs, but is not shown in the final document.

Add include = FALSE to the chunk. Remember to use a comma after the chunk label when adding chunk options.

Exercise: Add an option to the doacs_line chunk to hide the code which generates the line graph.

Add echo = FALSE to the chunk. echo prevents the code from appearing in the output file but not the results of the code. It’s often used for figures, where you want to show a chart but hide the code which generated the chart.

Exercise: Add an option to the doacs_table chunk to hide the message about summarise grouping.

Add message = FALSE.

Exercise: Override the global options in the setup chunk so every chunk runs and any results are generated, but the code is not shown.

Change to echo = FALSE in knitr::opts_chunk$set(echo = TRUE). We want to use echo = FALSE rather than include = FALSE as we still want to see our line chart and table.

Parameters

You can include parameters to rerun a report with different values. Parameters are specified in the YAML, given a default value (here, year: 2020), and used via params$name (e.g. params$year). (Note the backslash in here between params and name, visible only the .Rmd, is to escape the markdown syntax as dollar signs are used to display equations in markdown.)

# Changing the year to a parameter
doacs_df %>% 
    filter(year(date) == params$year) %>% 
    group_by(chemical, date) %>% 
    summarise(sum_items = sum(items)) %>% 
    reactable(
        .,
        groupBy = "chemical"
    )

Exercise: Try re-rendering the report with the year 2021 using the Rstudio IDE.

Click on the triangle next to ‘Knit’, ‘Knit with Parameters’, change 2020 to 2021.

Resources

• R4DS chapter on R markdown
• NHS-R community R markdown workshop
• Cheat sheet
• R markdown cookbook
• R markdown: The Definitive Guide